.TH C++SIM 3A "25 February 1995" "C++SIM" "C++SIM Reference Manual"
.SH NAME
Entity \- asynchronous simulation processes
.SH SYNOPSIS
.B "#ifndef ENTITY_H_"
.br
.B "#   include <Event/Entity.h>"
.br
.B "#endif"
.sp
.BI "class Entity : public Process"
.br
.BI "{"
.br
.BI "public:"
.br
.BI "	virtual ~Entity ();"
.sp
.BI "	Boolean Interrupt (Entity& toInterrupt,"
.br
.BI "					Boolean immediate = TRUE);"
.sp
.BI "	virtual void terminate ();"
.sp
.BI "	virtual void Body () = 0;
.sp
.BI "protected:"
.br
.BI "	Entity ();"
.sp
.BI "	Boolean Wait (double waitTime);
.br
.BI "	Boolean WaitFor (Entity& controller,"
.br
.BI "					Boolean reAct = FALSE);
.br
.BI "	Boolean WaitForTrigger (TriggerQueue& _queue);
.br
.BI "	void WaitForSemaphore (Semaphore& sem);
.br
.BI "};"
.SH DESCRIPTION
This class provides finer-grained control of simulation processes
than is available through the
.B
Process
class. Instances of these classes can be used to simulate asynchronous
events such as processor interrupts. However, since
.B
Entity
is derived from
.B
Process
all of the (synchronous) simulation controls are still available.

In addition to the states available to a
.B
Process
object, an asynchronous object can be in one of the following
states:

.I
	waiting
: the process is suspended waiting for a specific event to occur.
This process is 
.I
not
placed on the scheduler queue.

.I
	interrupted
: the process, which was in the
.I
waiting
state, has been interrupted before the condition it was waiting
for occurred.

.B
Interrupt
can be used to interrupt the specified process, which
.I
must
not be terminated and
.I
must
be in the
.I
waiting
state. The interrupted process becomes the next active process.
If the second paramater is
.B
TRUE
then the current process is immediately suspended, and scheduled
for reactivation at the current simulation time.

The conditions a process can wait for are:

.I
	time
: using the
.B
Wait
method, a process can attempt to wait for the specified simulation time,
and is placed in the
.I
waiting
state. The
method returns
.B
TRUE
if the process is interrupted before the time elapses.

.I
	process termination
: using the
.B
WaitFor
method, a process can wait for the termination of the
.B
controller
object, and is placed in the
.I
waiting
state. If the second parameter is
.B
TRUE
then
.B
controller
is moved to the head of the scheduler queue to become the next
active process, otherwise the application must activate it. If
the waiting process is interrupted before
.B
controller
terminates, then
.B
TRUE
is returned. The
.B
controller
and the waiting process
.I
must
be different, i.e., it is not possible for a process to
wait for itself.

.I
	semaphore
: critical regions of a simulation can be protected by semaphores.
Only a single
.B
Entity
object can acquire a semaphore; all others are suspended until the
semaphore is released. The
.B
WaitForSemaphore
method causes the current process to attempt to acquire the
.B
Semaphore
in the parameter. If this is not possible the process is suspended.
A process waiting on a semaphore cannot be interrupted, and is
.I
not
placed in the
.I
waiting
state. Therefore, when this method returns, the semaphore has
been acquired.

.I
	application specific
: other asynchronous events can be simulated using the
.B
WaitForTrigger
method. A
.B
TriggerQueue
maintains a list of
.B
Entity
objects waiting for specific events. This method places the object
on the specified queue and passivates it, placing it in the
.I
waiting
state. The queue methods can then be used to control reactivation. The
return value indicates whether the process was interrupted or
triggered.
.SH NOTES
Because instances of this class can be outside of the control of the
simulation
.B
scheduler
, deadlock situations can occur. Therefore, some care must
be taken when using these objects.
.SH SEE ALSO
Process(3A), Semaphore(3A), TriggerQueue(3A)
